home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 27 / CU Amiga Magazine's Super CD-ROM 27 (1998)(EMAP Images)(GB)[!][issue 1998-10].iso / CUCD / Programming / THXPlayLib / developer / thxplay.doc < prev   
Text File  |  1998-06-19  |  18KB  |  577 lines
  1. TABLE OF CONTENTS
  2.  
  3. thxplay.library/--overview--
  4. thxplay.library/thxFree
  5. thxplay.library/thxGetNumSongs
  6. thxplay.library/thxGetVolume
  7. thxplay.library/thxInit
  8. thxplay.library/thxNoteFX
  9. thxplay.library/thxPause
  10. thxplay.library/thxPlay
  11. thxplay.library/thxPlayNote
  12. thxplay.library/thxPlaytime
  13. thxplay.library/thxSetSong
  14. thxplay.library/thxSetVolume
  15. thxplay.library/thxSignalEnd
  16. thxplay.library/thxSongEnded
  17. thxplay.library/thxStop
  18. thxplay.library/thxStopNote
  19. thxplay.library/thxSyncByte
  20. thxplay.library/thxWind
  21. thxplay.library/--overview--                     thxplay.library/--overview--
  22.  
  23.    PURPOSE
  24.        To provide an interface to the THX2 player.
  25.  
  26.    OVERVIEW
  27.        THX2  is  a  'chip' music tracker by Martin Wodok (Dexter/Abyss). It
  28.        comes with a rather cumbersome binary replayer, so you may play THX2
  29.        songs  in  your  own  programs.  This  provides an easy and powerful
  30.        interface to the THX2 player, providing a wide range of functions.
  31.  
  32.         - Allocation: thxInit(), thxFree()
  33.         - Playing:    thxPlay(), thxStop(), thxPause(), thxWind()
  34.         - Volume:     thxGetVolume(), thxSetVolume()
  35.         - Multisong:  thxGetNumSongs(), thxSetSong()
  36.         - Sound FX:   thxPlayNote(), thxStopNote(), thxNoteFX()
  37.         - Misc:       thxSignalEnd(), thxSongEnded(), thxSyncByte(),
  38.                       thxPlaytime()
  39.  
  40.        You  need to read a THX song in from disk or 'incbin' it. You should
  41.        load  it  into  PUBLIC  memory,  however it does not have to be CHIP
  42.        memory.
  43.  
  44.        The  music  play  is,  as  you  would  expect, interrupt-driven, and
  45.        asynchronous. This interface automatically provides fallback support
  46.        for a VSYNC based replayer if it cannot allocate a CIA timer.
  47.  
  48.        The  interface is 68000 compatible, optimised versions for the 68020
  49.        and better are also included. The interface is available as an Amiga
  50.        E module, a shared library, or a C link-library.
  51.  
  52.    NOTE
  53.        This  interface was initially developed as an Amiga E module. With a
  54.        little  extra  effort,  it  is  also  available  as a runtime shared
  55.        library.  Therefore, it operates a simple mechanism in thxInit() and
  56.        thxFree()  to ensure only one task at any time is using the library.
  57.        See the notes of thxInit() for more information about this.
  58.  
  59.        Also note that all examples are given in Amiga E code.
  60.  
  61.        Synopsis is given as 3 lines: the assembler/register synopsis, the C
  62.        prototype,  and the E synopsis.
  63.  
  64.    EXAMPLE
  65.        More thorough examples are included with the distribution.
  66.        This is an example in Amiga E, using the E module thx-play.m.
  67.  
  68.        MODULE 'tools/thx-play', 'tools/file'
  69.        PROC main()
  70.          DEF mod
  71.          IF mod := loadfile(arg, 0, MEMF_PUBLIC)
  72.            IF thxInit(mod)=0
  73.              thxPlay()
  74.              REPEAT; WaitTOF(); UNTIL CtrlC() OR thxSongEnded()
  75.              thxStop()
  76.  
  77.              thxFree()
  78.            ENDIF
  79.            freefile(mod)
  80.          ENDIF
  81.        ENDPROC
  82.  
  83.        Here is the same example, but using the shared thxplay.library.
  84.        Note that Amiga E forces library functions to have capitalised
  85.        names, and that we must use OpenLibrary() and CloseLibrary().
  86.  
  87.        MODULE 'thxplay', 'tools/file'
  88.        PROC main()
  89.          DEF mod
  90.          IF thxplaybase := OpenLibrary('thxplay.library', 5)
  91.            IF mod := loadfile(arg, 0, MEMF_PUBLIC)
  92.              IF ThxInit(mod) = 0
  93.                ThxPlay()
  94.                REPEAT; WaitTOF(); UNTIL CtrlC() OR ThxSongEnded()
  95.                ThxStop()
  96.  
  97.                ThxFree()
  98.              ENDIF
  99.              freefile(mod)
  100.            ENDIF
  101.            CloseLibrary(thxplaybase)
  102.          ENDIF
  103.        ENDPROC
  104.  
  105.  
  106. thxplay.library/thxFree                               thxplay.library/thxFree
  107.  
  108.    NAME
  109.        thxFree -- free resources held by player.
  110.  
  111.    SYNOPSIS
  112.        void thxFree()
  113.  
  114.        void thxFree(void);
  115.  
  116.        thxFree()
  117.  
  118.    FUNCTION
  119.        Stops any THX module playing and frees resources used by the player.
  120.        You can call this whether thxInit() suceeded or not.
  121.  
  122.    SEE ALSO
  123.        thxInit()
  124.  
  125. thxplay.library/thxGetNumSongs                 thxplay.library/thxGetNumSongs
  126.  
  127.    NAME
  128.        thxGetNumSongs -- get number of subsongs.
  129.  
  130.    SYNOPSIS
  131.        songs = thxGetNumSongs()
  132.        D0-0:7
  133.  
  134.        ULONG thxGetNumSongs(void);
  135.  
  136.        songs := thxGetNumSongs()
  137.  
  138.    FUNCTION
  139.        Returns  the  number  of subsongs in the module, if any. You can use
  140.        the  thxSetSong()  function  to  play one of the subsongs, if that's
  141.        possible.
  142.  
  143.    RESULT
  144.        songs - 0 if there are no subsongs (only the main song), otherwise
  145.                returns the number of subsongs.
  146.  
  147.    SEE ALSO
  148.        thxSetSong()
  149.  
  150. thxplay.library/thxGetVolume                     thxplay.library/thxGetVolume
  151.  
  152.    NAME
  153.        thxGetVolume -- get master volume.
  154.  
  155.    SYNOPSIS
  156.        volume = thxGetVolume()
  157.        D0-0:6
  158.  
  159.        ULONG thxGetVolume(void);
  160.  
  161.        volume := thxGetVolume()
  162.  
  163.    FUNCTION
  164.        Returns the current master volume value. Does not stop play.
  165.  
  166.    RESULT
  167.        volume - current volume setting from 0 (silent) to 64 (loudest)
  168.  
  169.    SEE ALSO
  170.        thxSetVolume()
  171.  
  172. thxplay.library/thxInit                               thxplay.library/thxInit
  173.  
  174.    NAME
  175.        thxInit -- initialise player and module.
  176.  
  177.    SYNOPSIS
  178.        error = thxInit(module)
  179.        D0              A0
  180.  
  181.        ULONG thxInit(APTR);
  182.  
  183.        error := thxInit(module)
  184.  
  185.    FUNCTION
  186.        Initialises  the  player (if needed) and initializes the module. You
  187.        may  also  call  thxInit(NIL)  to  initialise the player but not the
  188.        module.  Does not start to play the module until you call thxPlay().
  189.        You  must  call  this each time you want to play a different module.
  190.        The allocations made for the player are made only the first time you
  191.        call  thxInit(), no matter how many modules you want. If allocations
  192.        fail, they will be automatically freed.
  193.  
  194.    INPUTS
  195.        module - pointer to a THX module or NIL
  196.  
  197.    RESULT
  198.        error - zero means all went OK, any other value means failure.
  199.  
  200.    NOTE
  201.        In  the  library  version of this interface, thxInit() and thxFree()
  202.        use  a task ownership system - to begin with, nobody 'owns' THX. The
  203.        first  task  to  call  thxInit() will then 'own' THX, and successive
  204.        calls  to  thxInit()  and thxFree() will only succeed for this task.
  205.        When  this  task calls thxFree(), the owner goes back to nobody, and
  206.        now other tasks are free to use THX.
  207.  
  208.        This  is the only arbitration used by the interface. All other calls
  209.        may  be called from any task at all. Please respect this arbitration
  210.        mechanism and avoid calling other THX functions unless thxInit() has
  211.        succeeded  for  you. You must call thxFree() from the same task that
  212.        called thxInit().
  213.  
  214.    SEE ALSO
  215.        thxFree(), thxPlay()
  216.  
  217. thxplay.library/thxNoteFX                           thxplay.library/thxNoteFX
  218.  
  219.    NAME
  220.        thxNoteFX -- perform FX command on user-specified channel.
  221.  
  222.    SYNOPSIS
  223.        void thxNoteFX(channel, command, parameter)
  224.                       D0-0:1   D1-0:3   D2-0:7
  225.  
  226.        void thxNoteFX(ULONG, ULONG, ULONG);
  227.  
  228.        thxNoteFX(channel, command, parameter)
  229.  
  230.    FUNCTION
  231.        Performs  an  effect command on the particular channel. You can call
  232.        this  at  any  time,  even before you play the note, if you want the
  233.        note  to  start  off  with an initial effect. See THX Sound System's
  234.        documentation for the full list of commands and their parameters.
  235.  
  236.    INPUTS
  237.        channel   - The channel affected
  238.        command   - the effect command, eg $C is the Set Volume command.
  239.        parameter - the parameter to the command, eg $40 is full volume.
  240.  
  241.    NOTE
  242.        No  validation  of  the  command  or  its  parameter is done. Beware
  243.        feeding wrong or out of range values. Range for command is $0 to $F,
  244.        parameter is $00 to $FF.
  245.  
  246.    SEE ALSO
  247.        thxPlayNote()
  248.  
  249. thxplay.library/thxPause                             thxplay.library/thxPause
  250.  
  251.    NAME
  252.        thxPause -- pause play of a song.
  253.  
  254.    SYNOPSIS
  255.        void thxPause()
  256.  
  257.        void thxPause(void);
  258.  
  259.        thxPause()
  260.  
  261.    FUNCTION
  262.        Pauses the playing module. Call thxPlay() to continue play again.
  263.  
  264.    SEE ALSO
  265.        thxPlay()
  266.  
  267. thxplay.library/thxPlay                               thxplay.library/thxPlay
  268.  
  269.    NAME
  270.        thxPlay -- start playing the song.
  271.  
  272.    SYNOPSIS
  273.        void thxPlay()
  274.  
  275.        void thxPlay(void);
  276.  
  277.        thxPlay()
  278.  
  279.    FUNCTION
  280.        Starts  playing  the module. If the module has just been initialised
  281.        or  stopped,  or  the  subsong has just been changed, then play will
  282.        start  at  the  beginning  of  the  song/subsong. Otherwise, it will
  283.        continue from where it was paused.
  284.  
  285.    SEE ALSO
  286.        thxStop(), thxPause()
  287.  
  288. thxplay.library/thxPlayNote                       thxplay.library/thxPlayNote
  289.  
  290.    NAME
  291.        thxPlayNote -- start playing a user-specified note.
  292.  
  293.    SYNOPSIS
  294.        void thxPlayNote(channel, note,   instrument)
  295.                         D0-0:1   D1-0:5  D2-0:5
  296.  
  297.        void thxPlayNote(ULONG, ULONG, ULONG);
  298.  
  299.        thxPlayNote(channel, note, instrument)
  300.  
  301.    FUNCTION
  302.        Plays  one of the instruments in the THX module at a particular note
  303.        on  a particular channel. It is up to you to ensure that the channel
  304.        you  play  the  note  on is empty and so will not interfere with the
  305.        note  being  played.  This function is to allow you to play your own
  306.        notes  during  THX  play,  for  example  as  part of a game as sound
  307.        effects.  The  note  played is subject to the same conditions as the
  308.        song itself, such as the global volume control. In addition, you can
  309.        apply  'FX'  commands to the note. In effect, what is happening when
  310.        you  call  thxPlayNote()  is  that  the  'track data' for the chosen
  311.        channel being played is overwritten (not the module itself, just the
  312.        sound output). It is overwritten on the first line by your specified
  313.        instrument  with  note  and  FX,  then  on  consecutive lines by the
  314.        'blank'  note and instrument. This 'overwriting' stops only when you
  315.        call thxStopNote(), or stop the module naturaly.
  316.  
  317.    INPUTS
  318.        channel    - The channel on which the note is played, from 0 to 3.
  319.        note       - The halfnote (pitch) at which the instrument is to be
  320.                     played, from 1 (C-1) to 60 (B-5).
  321.        instrument - an instrument from the song, from 1-63. You should know
  322.                     which instrument you want to play!
  323.  
  324.    EXAMPLE
  325.        thxPlayNote(2, 8, 12) is equivalent to this in THX Sound System's
  326.        tracker view:
  327.  
  328.        ---00000 | ---00000 | G-112000 | ---00000
  329.        ---00000 | ---00000 | ---00000 | ---00000
  330.        ---00000 | ---00000 | ---00000 | ---00000
  331.        [...]
  332.  
  333.    SEE ALSO
  334.        thxStopNote(), thxNoteFX()
  335.  
  336. thxplay.library/thxPlaytime                       thxplay.library/thxPlaytime
  337.  
  338.    NAME
  339.        thxPlaytime -- get current playtime of song.
  340.  
  341.    SYNOPSIS
  342.        seconds [, ticks] = thxPlaytime()
  343.        D0         D1
  344.  
  345.        ULONG thxPlaytime(void);
  346.  
  347.        seconds, ticks := thxPlaytime()
  348.  
  349.    FUNCTION
  350.        Gets the current playtime into the play of a currently playing song.
  351.  
  352.    RESULT
  353.        seconds - the number of seconds elapsed since the start of the song.
  354.        ticks   - the above, in internal clock ticks instead
  355.  
  356.   BUGS
  357.        Will wrap at 65536 seconds (18 hours).
  358.  
  359.   NOTE
  360.        Most C compilers will be unable to get the second result, ticks. Too
  361.        bad. It's not that important.
  362.  
  363. thxplay.library/thxSetSong                         thxplay.library/thxSetSong
  364.  
  365.    NAME
  366.        thxSetSong -- set song to be played.
  367.  
  368.    SYNOPSIS
  369.        thxSetSong(song)
  370.                   D0-0:7
  371.  
  372.        void thxSetSong(ULONG);
  373.  
  374.        thxSetSong(song)
  375.  
  376.    FUNCTION
  377.        Sets  which  song  to play, if a module contains more than one song.
  378.        Most  modules  only  contain  one  song,  but  some  modules contain
  379.        sub-songs  as  well  as  the  main one. You can use this function to
  380.        specify  which  one  should be played. If you call this function and
  381.        there is already a song playing, it will be stopped first.
  382.  
  383.    INPUTS
  384.        song - 0 to set the main song to be played, any other number will
  385.               change to that subsong, if it exists. Otherwise, no change
  386.               will be made (other than the stoppage).
  387.  
  388.    NOTE
  389.        It is up to you to start playing the module again.
  390.  
  391.    SEE ALSO
  392.        thxGetNumSongs()
  393.  
  394. thxplay.library/thxSetVolume                     thxplay.library/thxSetVolume
  395.  
  396.    NAME
  397.        thxSetVolume -- set master volume.
  398.  
  399.    SYNOPSIS
  400.        void thxSetVolume(volume)
  401.                          D0-0:6
  402.  
  403.        void thxSetVolume(ULONG);
  404.  
  405.        thxSetVolume(volume)
  406.  
  407.    FUNCTION
  408.        Sets the master volume. Does not stop play.
  409.  
  410.    INPUTS
  411.        volume - from 0 (silent) to 64 (loudest)
  412.  
  413.    NOTE
  414.        This  function  can take up to two frames to take an audible effect.
  415.        If the song is paused, will not take effect until unpaused.
  416.  
  417.    SEE ALSO
  418.        thxGetVolume()
  419.  
  420. thxplay.library/thxSignalEnd                     thxplay.library/thxSignalEnd
  421.  
  422.    NAME
  423.        thxSignalEnd -- Signal() when song ends.
  424.  
  425.    SYNOPSIS
  426.        thxSignalEnd(task, signalset)
  427.                     A0    D0
  428.  
  429.        void thxSignalEnd(struct Task *, ULONG);
  430.  
  431.        thxSignalEnd(task, signalset)
  432.  
  433.    FUNCTION
  434.        Asks  THX  to send the signalset to the specified task when the song
  435.        ends.  If songend occurs and the signal is sent, it will not be sent
  436.        again  unless  you  call thxSignalEnd() again to reload the trigger.
  437.        The signal will also be cancelled if you call thxStop() directly, or
  438.        indirectly through thxSetSong() or thxFree().
  439.  
  440.    NOTE
  441.        The detection of songend is crap (sorry Dexter :^)
  442.  
  443.    INPUTS
  444.        task       - pointer  to  a  task  or  process structure, simply use
  445.                     FindTask(NIL) to send to yourself.
  446.        signalset  - a 32bit set of signals, to be sent to task when songend
  447.                     occurs.
  448.  
  449.    EXAMPLE
  450.        thxSignalEnd(FindTask(NIL), SIGBREAKF_CTRL_C) will send you a CTRL-C
  451.        when the song ends.
  452.  
  453.    SEE ALSO
  454.        thxSongEnded(), exec.library/Signal()
  455.  
  456. thxplay.library/thxSongEnded                     thxplay.library/thxSongEnded
  457.  
  458.        thxSongEnded -- detect if song has ended.
  459.  
  460.    SYNOPSIS
  461.        songended = thxSongEnded()
  462.        D0
  463.  
  464.        BOOL thxSongEnded(void);
  465.  
  466.        songended := thxSongEnded()
  467.  
  468.    FUNCTION
  469.        Returns  nonzero  value if the player has detected the end of a song
  470.        and is now looping.
  471.  
  472.    NOTE
  473.        The detection of songend is crap (sorry Dexter :^)
  474.  
  475.    RESULT
  476.        songended - nonzero if song is now looping, zero otherwise.
  477.  
  478.    SEE ALSO
  479.        thxSignalEnd()
  480.  
  481. thxplay.library/thxStop                               thxplay.library/thxStop
  482.  
  483.    NAME
  484.        thxStop -- stop playing a song/module.
  485.  
  486.    SYNOPSIS
  487.        void thxStop()
  488.  
  489.        void thxStop(void);
  490.  
  491.        thxStop()
  492.  
  493.    FUNCTION
  494.        Stops  the  module.  Can  be restarted from the beginning again with
  495.        thxPlay().
  496.  
  497.    SEE ALSO
  498.        thxPlay(), thxFree()
  499.  
  500. thxplay.library/thxStopNote                       thxplay.library/thxStopNote
  501.  
  502.    NAME
  503.        thxStopNote -- stop playing user-specified note.
  504.  
  505.    SYNOPSIS
  506.        void thxStopNote(channel)
  507.                         D0-0:1
  508.  
  509.        void thxStopNote(ULONG);
  510.  
  511.        thxStopNote(channel)
  512.  
  513.    FUNCTION
  514.        Stops  anything you started with thxPlayNote(). Please be aware that
  515.        notes  which  don't  fade  away  on  their own will first need to be
  516.        silenced with thxNoteFX($C, $00), or such
  517.  
  518.    SEE ALSO
  519.        thxPlayNote()
  520.  
  521. thxplay.library/thxSyncByte                       thxplay.library/thxSyncByte
  522.  
  523.    NAME
  524.        thxSyncByte -- get sync byte value.
  525.  
  526.    SYNOPSIS
  527.        syncvalue = thxSyncByte()
  528.        D0-0:7
  529.  
  530.        ULONG thxSyncByte(void);
  531.  
  532.        syncvalue := thxSyncByte()
  533.  
  534.    FUNCTION
  535.        Gets the current setting of the 'external timing' byte, which can be
  536.        set  to any byte value at any moment in time during play of the song
  537.        BY  the  song  itself,  using  the '8' command  in the tracker. This
  538.        function  is  here to allow you to mark specific events in the music
  539.        with   the  '8'  command  and  a  value,  then  wait  until  calling
  540.        thxSyncByte()  returns that value. The returned value doesn't change
  541.        until another '8' command in the song changes it.
  542.  
  543.    NOTE
  544.        Be  very  careful  not  to  busy-wait on a new value if there is the
  545.        possibility the song is paused or not playing.
  546.  
  547.    RESULT
  548.        syncvalue - current value of the sync byte.
  549.  
  550. thxplay.library/thxWind                               thxplay.library/thxWind
  551.  
  552.    NAME
  553.        thxWind -- wind the song forward or back.
  554.  
  555.    SYNOPSIS
  556.        void thxWind(direction)
  557.                     D0
  558.  
  559.        void thxWind(ULONG);
  560.  
  561.        thxWind(direction)
  562.  
  563.    FUNCTION
  564.        Advances forward or backwards through the song by a specified number
  565.        of positions. Please use the values 1 to skip forward and -1 to skip
  566.        back, for future compatibility.
  567.  
  568.    INPUTS
  569.        direction - if  1, winds on to the next position.
  570.                    if -1, winds back to the previous position,
  571.                    if  0, ignored.
  572.  
  573.    NOTE
  574.        Be  wary  of  stepping  beyond  the  end  of  a song. Also note this
  575.        function only takes effect only once a frame.
  576.  
  577.